To start using Elementary, you need to add our dbt package to your dbt project.

<Accordion title="What are dbt packages and packages.yml?">
A dbt package is additional Jinja and SQL code that is added to your project, for additional functionality. In fact, each package is a dbt project. By adding a package to your project, you are adding the package code to be part of your project, you can reference its macros, execute its models, and so on.

Add packages to your project by creating a `packages.yml` file under the main project directory (where your `dbt_project.yml` is), and adding the relevant package. After you add a new package, run `dbt deps` to actually pull its code to your project. This is also how you update packages.
Some packages we recommend you check out: [dbt_utils](https://github.com/dbt-labs/dbt-utils/tree/0.8.2/), [dbt_date](https://github.com/calogica/dbt-date/tree/0.5.4/), [codegen](https://github.com/dbt-labs/dbt-codegen/tree/0.5.0/).

</Accordion>

## Video: How to install Elementary dbt package?

<Frame>
  <div style={{ paddingBottom: "64.98194945848375%" }}>
    <iframe
      src="https://www.loom.com/embed/5cf1aaa0708f43a993f8a2945473c7ac"
      frameborder="0"
      webkitAllowFullscreen
      mozAllowFullScreen
      allowFullScreen
      style={{
        position: "absolute",
        top: 0,
        left: 0,
        width: "100%",
        height: "100%",
      }}
    ></iframe>
  </div>
</Frame>

## Step-by-step: Install Elementary dbt package

<Steps>
  <Step title="Add elementary to `packages.yml`">
    
    Add the following to your `packages.yml` file (if missing, create it where `dbt_project.yml` is):
    
    ```yml packages.yml
    packages:
      - package: elementary-data/elementary
        version: 0.15.2
        ## Docs: https://docs.elementary-data.com
    ```
  </Step>
  <Step title="Add to your `dbt_project.yml`">
    <Info>
        This means Elementary models will have their own schema.
        Depending on your project [custom schema macro](https://docs.getdbt.com/docs/build/custom-schemas), the schema will be named `elementary` or `<target_schema>_elementary`. 
        Make sure your user has permissions to create schemas.
    </Info>
    
    <Accordion title="Important: Materialization config">
        
        For elementary to work, it needs to create some of the models as incremental tables.
        Make sure that there are no global materialization configurations that affect elementary, such as:
        
        ```yml dbt_project.yml
        materialized: "{{ 'table' if target.name == 'prod-cloud' else 'view' }}"
        ```
        
        Make sure to place the 'elementary' configuration under the models key, and other configs under your project name.
        
        Example:
        
        ```yml dbt_project.yml
        models:
          my_project:
            materialized: "{{ 'table' if target.name == 'prod-cloud' else 'view' }}"
        
          elementary:
            +schema: "elementary"
        ```
        
        **If you change materialization settings, make sure to run `dbt run -s elementary --full-refresh`.**
        
    </Accordion>
    <Accordion title="Important: Allowing Elementary to override dbt's default materializations (relevant from dbt 1.8)">
        <Snippet file="dbt-18-materializations-common.mdx" />

        In order for these features to work, it is required to add the following flag to your `dbt_project.yml` file:
        ```yml dbt_project.yml
        flags:
          require_explicit_package_overrides_for_builtin_materializations: false
        ```

        Please note that after setting this flag you may see a deprecation warning from dbt.
        This is a temporary measure and we are working with the dbt team on a [longer term solution](https://github.com/dbt-labs/dbt-core/issues/10090).
    </Accordion>
    
    ```yml dbt_project.yml
    models:
      ## see docs: https://docs.elementary-data.com/
      elementary:
        ## elementary models will be created in the schema '<your_schema>_elementary'
        +schema: "elementary"
        ## To disable elementary for dev, uncomment this:
        # enabled: "{{ target.name in ['prod','analytics'] }}"
    
    # Required from dbt 1.8 and above for certain Elementary features (please see more details above)
    flags:
      require_explicit_package_overrides_for_builtin_materializations: false
    ```
  </Step>
  <Step title="Import the package and build Elementary models">

    ```shell Terminal
    dbt deps
    dbt run --select elementary
    ```
    This will mostly create empty tables, that will be updated with artifacts, metrics and test results in your future dbt executions.

  </Step>
  <Step title="Run tests">

    Validate the installation by running some tests:

    ```shell Terminal
    dbt test
    ```

    After you ran your tests, we recommend that you ensure that the results were loaded to `elementary_test_results` table.

  </Step>
</Steps>

## What happens now?

Once the elementary dbt package has been installed and configured, your test results, run results and [dbt artifacts](/dbt/dbt-artifacts) will be loaded to elementary schema tables.

If you see data in these models you completed the package deployment (Congrats! 🎉).
